Pular para conteúdo

2. Tutorial

Bem-vindo ao tutorial do PixCore! No Guia de Início Rápido, você aprendeu a gerar um QR Code Pix básico. Agora, vamos explorar funcionalidades mais avançadas, como customização de cores, adição de logos e a manipulação da imagem do QR Code em memória.

1. Gerando um Pix sem Valor Definido

Um caso de uso muito comum é gerar um QR Code onde o pagador pode inserir o valor que desejar. Para fazer isso, basta omitir o parâmetro valor ou defini-lo como None ao criar seu objeto PixData.

from pixcore.models import PixData
from pixcore.brcode import Pix

# 1. Crie os dados sem o campo "valor"
dados_pix_livre = PixData(
    recebedor_nome="ONG BEM MAIOR",
    recebedor_cidade="BRASILIA",
    pix_key="projetobemmaior@email.com", # Chave do tipo e-mail
    transacao_id="DOACAO123"
)

# 2. Instancie o gerador
gerador_pix = Pix(dados_pix_livre)

# 3. Salve o QR Code
gerador_pix.save_qrcode("pix_sem_valor.png")

print("QR Code para doação (valor livre) salvo com sucesso!")`

O arquivo pix_sem_valor.png gerado permitirá que o usuário defina o valor a ser pago no app do banco.

2. Customização Visual do QR Code

A biblioteca permite personalizar a aparência do QR Code de duas formas principais: adicionando um logo e alterando as cores.

Você pode embutir uma imagem (como o logo da sua marca) no centro do QR Code. Para isso, a biblioteca usa um nível de correção de erros alto, garantindo que o código continue legível.

Importante: O logo deve estar em um formato de imagem comum (.png, .jpg) e não pode ser muito grande para não comprometer a leitura.

# Reutilizando os dados do exemplo anterior
dados_pix_com_valor = PixData(
    recebedor_nome="CAFETERIA DO JOSE",
    recebedor_cidade="RIO DE JANEIRO",
    pix_key="pagamento@cafeteriajose.com.br",
    valor=15.00,
    transacao_id="CAFE-PEDIDO-456"
)

gerador_pix = Pix(dados_pix_com_valor)

# Use o parâmetro "caminho_logo" para especificar a imagem
gerador_pix.save_qrcode(
    "pix_com_logo.png",
    caminho_logo="caminho/para/seu/logo.png" # Altere para o caminho real do seu logo
)
print("QR Code com logo salvo!")

2.2. Alterando as Cores

É possível alterar a cor de preenchimento do QR Code e a cor do fundo usando os parâmetros cor_qr e cor_fundo. Você pode usar nomes de cores em inglês (ex: "navy") ou códigos hexadecimais (ex: "#000080").

# Reutilizando o mesmo gerador
gerador_pix.save_qrcode(
    "pix_colorido.png",
    cor_qr="navy",       # Cor dos blocos do QR Code
    cor_fundo="#EFEFEF"  # Cor de fundo
)
print("QR Code colorido salvo!")

3. Manipulando o QR Code em Memória

E se você não quiser salvar o QR Code em um arquivo? Por exemplo, para exibi-lo em uma página web com Flask/Django ou inseri-lo em um PDF com reportlab.

Para isso, use o método .qrcode() em vez de .save_qrcode(). Ele retorna um objeto de imagem da biblioteca Pillow (PIL), que você pode manipular como quiser.

from pixcore.models import PixData
from pixcore.brcode import Pix

dados_pix = PixData(
    recebedor_nome="LOJA ONLINE",
    recebedor_cidade="CURITIBA",
    pix_key="vendas@lojaonline.com",
    valor=99.90,
    transacao_id="WEB-VENDA-789"
)
gerador_pix = Pix(dados_pix)

# 1. Gere a imagem do QR Code em memória
imagem_qr = gerador_pix.qrcode()

# 2. Agora você tem um objeto de imagem. Você pode:
#    - Exibi-la (bom para testes e scripts locais)
print("Exibindo imagem em uma janela...")
imagem_qr.show()

Este método oferece máxima flexibilidade para integrar o QR Code em qualquer fluxo de trabalho da sua aplicação.

4. Tratamento de Erros

Como visto no início, a classe PixData protege sua aplicação de dados inválidos. É uma boa prática sempre envolver a criação de PixData em um bloco try...except para capturar e tratar esses erros de forma elegante.

try:
    # Tentando criar um Pix com um nome de recebedor longo demais
    dados_errados = PixData(
        recebedor_nome="UM NOME DE EMPRESA EXTREMAMENTE LONGO QUE VAI CAUSAR UM ERRO DE VALIDACAO",
        recebedor_cidade="SAO PAULO",
        pix_key="chave-valida@email.com"
    )
except ValueError as e:
    print(f"Ocorreu um erro esperado: {e}")

Com isso, você tem uma visão completa de como utilizar os principais recursos do PixCore. Para detalhes sobre cada parâmetro e método, consulte a Referência da API.